home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kprotocolmanager.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-01-19  |  11.0 KB  |  390 lines
  1. /* This file is part of the KDE libraries
  2.    Copyright (C) 1999 Torben Weis <weis@kde.org>
  3.    Copyright (C) 2000- Waldo Bastain <bastain@kde.org>
  4.    Copyright (C) 2000- Dawit Alemayehu <adawit@kde.org>
  5.  
  6.    This library is free software; you can redistribute it and/or
  7.    modify it under the terms of the GNU Library General Public
  8.    License version 2 as published by the Free Software Foundation.
  9.  
  10.    This library is distributed in the hope that it will be useful,
  11.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.    Library General Public License for more details.
  14.  
  15.    You should have received a copy of the GNU Library General Public License
  16.    along with this library; see the file COPYING.LIB.  If not, write to
  17.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.    Boston, MA 02110-1301, USA.
  19. */
  20. #ifndef __kprotocolmanager_h__
  21. #define __kprotocolmanager_h__
  22.  
  23. #include <qstringlist.h>
  24.  
  25. #include <kapplication.h>
  26. #include <kio/global.h>
  27.  
  28. /** @deprecated Use KProtocolManager::defaultUserAgent() instead. */
  29. #define DEFAULT_USERAGENT_STRING ""
  30.  
  31. class KConfig;
  32.  
  33. /**
  34.  * Provides information about I/O (Internet, etc.) settings chosen/set
  35.  * by the end user.
  36.  *
  37.  * KProtocolManager has a heap of static functions that allows only read
  38.  * access to KDE's IO related settings. These include proxy, cache, file
  39.  * transfer resumption, timeout and user-agent related settings.
  40.  *
  41.  * The information provided by this class is generic enough to be applicable
  42.  * to any application that makes use of KDE's IO sub-system.  Note that this
  43.  * mean the proxy, timeout etc. settings are saved in a separate user-specific
  44.  * config file and not in the config file of the application.
  45.  *
  46.  * Original author:
  47.  * @author Torben Weis <weis@kde.org>
  48.  *
  49.  * Revised by:
  50.  * @author Waldo Bastain <bastain@kde.org>
  51.  * @author Dawit Alemayehu <adawit@kde.org>
  52.  * @see KPAC
  53.  */
  54. class KIO_EXPORT KProtocolManager
  55. {
  56. public:
  57.  
  58.  
  59. /*=========================== USER-AGENT SETTINGS ===========================*/
  60.  
  61.  
  62.   /**
  63.    * Returns the default user-agent string.
  64.    *
  65.    * @return the default user-agent string
  66.    */
  67.   static QString defaultUserAgent();
  68.  
  69.   /**
  70.    * Returns the default user-agent value.
  71.    *
  72.    * @param keys can be any of the following:
  73.    * @li 'o'    Show OS
  74.    * @li 'v'    Show OS Version
  75.    * @li 'p'    Show platform
  76.    * @li 'm'    Show machine architecture
  77.    * @li 'l'    Show language
  78.    * @return the default user-agent value with the given @p keys
  79.    */
  80.   static QString defaultUserAgent(const QString &keys);
  81.  
  82.   /**
  83.    * Returns the userAgent string configured for the
  84.    * specified host.
  85.    *
  86.    * If hostname is not found or is empty (i.e. "" or
  87.    * QString::null) this function will return the default
  88.    * user agent.
  89.    *
  90.    * @param hostname name of the host
  91.    * @return specified userAgent string
  92.    */
  93.   static QString userAgentForHost( const QString &hostname );
  94.  
  95.  
  96. /*=========================== TIMEOUT CONFIG ================================*/
  97.  
  98.  
  99.   /**
  100.    * Returns the preferred timeout value for reading from
  101.    * remote connections in seconds.
  102.    *
  103.    * @return timeout value for remote connection in secs.
  104.    */
  105.   static int readTimeout();
  106.  
  107.   /**
  108.    * Returns the preferred timeout value for remote connections
  109.    * in seconds.
  110.    *
  111.    * @return timeout value for remote connection in secs.
  112.    */
  113.   static int connectTimeout();
  114.  
  115.   /**
  116.    * Returns the preferred timeout value for proxy connections
  117.    * in seconds.
  118.    *
  119.    * @return timeout value for proxy connection in secs.
  120.    */
  121.   static int proxyConnectTimeout();
  122.  
  123.   /**
  124.    * Returns the preferred response timeout value for
  125.    * remote connecting in seconds.
  126.    *
  127.    * @return timeout value for remote connection in seconds.
  128.    */
  129.   static int responseTimeout();
  130.  
  131.  
  132. /*=============================== PROXY CONFIG ==============================*/
  133.  
  134.  
  135.   /**
  136.    * Returns true if the user specified a proxy server to make connections.
  137.    *
  138.    * @see slaveProtocol, proxyForURL, proxyFor
  139.    */
  140.   static bool useProxy();
  141.  
  142.   /**
  143.    * Returns true if the proxy settings should apply to the list
  144.    * returned by @ref noProxyFor.
  145.    *
  146.    * Normally addresses listed in the noProxyFor list are not routed
  147.    * through a proxy server. However, if this function returns true,
  148.    * then all addresses listed in the noProxyFor list are to be routed
  149.    * through a proxy server where as those that are not should bypass it.
  150.    *
  151.    * This function as well as @ref noProxyFor only apply when @ref proxyType
  152.    * is @p ManualProxy.
  153.    *
  154.    * @see proxyForURL, proxyFor, slaveProtocol
  155.    */
  156.   static bool useReverseProxy();
  157.  
  158.   /**
  159.    * Types of proxy configuration
  160.    * @li NoProxy     - No proxy is used
  161.    * @li ManualProxy - Proxies are manually configured
  162.    * @li PACProxy    - A Proxy configuration URL has been given
  163.    * @li WPADProxy   - A proxy should be automatically discovered
  164.    * @li EnvVarProxy - Use the proxy values set through environment variables.
  165.    */
  166.   enum ProxyType
  167.   {
  168.       NoProxy,
  169.       ManualProxy,
  170.       PACProxy,
  171.       WPADProxy,
  172.       EnvVarProxy
  173.   };
  174.  
  175.   /**
  176.    * Returns the type of proxy configuration that is used.
  177.    *
  178.    * @see ProxyType
  179.    */
  180.   static ProxyType proxyType();
  181.  
  182.   /**
  183.    * Proxy authorization modes.
  184.    *
  185.    * @li Prompt     - Ask for authorization as needed
  186.    * @li Automatic  - Use auto login as defined in .kionetrc files.
  187.    *
  188.    * NOTE: .kionetrc files have the same format as ftp .netrc files.
  189.    * Please note the use of .kionetrc files is highly discouraged since
  190.    * password is stored in clear text. For future releases the ability
  191.    * to store preset password for proxy servers will probably be supported
  192.    * through KWallet integration.
  193.    */
  194.   enum ProxyAuthMode
  195.   {
  196.       Prompt,
  197.       Automatic
  198.   };
  199.  
  200.   /**
  201.    * Returns the way proxy authorization should be handled.
  202.    *
  203.    * @see ProxyAuthMode
  204.    */
  205.   static ProxyAuthMode proxyAuthMode();
  206.  
  207.   /**
  208.    * Returns a comma-separated list of hostnames or partial
  209.    * host-names that should bypass any proxy settings.
  210.    *
  211.    * This function as well as @ref useReverseProxy only apply
  212.    * when @ref proxyType is @p ManualProxy.
  213.    *
  214.    * @see useReverseProxy, proxyFor, proxyForURL, slaveProtocol
  215.    */
  216.   static QString noProxyFor();
  217.  
  218.   /**
  219.    * Same as above except the environment variable name
  220.    * is returned instead of the variable value when
  221.    * @ref proxyType is @p EnvVarProxy.
  222.    *
  223.    * @see noProxyFor
  224.    * @since 3.5.x
  225.    */
  226.   static QString noProxyForRaw();
  227.  
  228.   /**
  229.    * Returns the proxy server address for a given protocol.
  230.    *
  231.    * NOTE: This function does not take the @ref useReverseProxy()
  232.    * settings into account.
  233.    *
  234.    * @see useReverseProxy, slaveProtocol
  235.    * @param protocol the protocol whose proxy info is needed
  236.    * @returns the proxy server address if one is available,
  237.    *          or QString::null if not available
  238.    */
  239.   static QString proxyFor( const QString& protocol );
  240.  
  241.   /**
  242.    * Returns the proxy server address for a given URL.
  243.    *
  244.    * If @ref proxyType returns Automatic, an external service
  245.    * called KPAC (a kded module) is used to determine the proxy
  246.    * server. Otherwise, @ref proxyFor is invoked to determine
  247.    * whether the URL needs to be routed through a proxy server.
  248.    *
  249.    * NOTE: This function does not take the @ref useReverseProxy()
  250.    * or the @ref noProxyFor() settings into account.
  251.    *
  252.    * @see useReverseProxy, slaveProtocol, noProxyFor
  253.    * @param url the URL whose proxy info is needed
  254.    * @returns the proxy server address or the text "DIRECT"
  255.    *          if no proxying is needed for the given address.
  256.    */
  257.   static QString proxyForURL( const KURL& url );
  258.  
  259.   /**
  260.    * Marks this proxy as bad (down). It will not be used for the
  261.    * next 30 minutes. (The script may supply an alternate proxy)
  262.    * @param proxy the proxy to mark as bad (as URL)
  263.    */
  264.   static void badProxy( const QString & proxy );
  265.  
  266.   /**
  267.    * Returns the URL of the script for automatic proxy configuration.
  268.    * @return the proxy configuration script
  269.    */
  270.   static QString proxyConfigScript();
  271.  
  272.  
  273. /*========================== CACHE CONFIG ===================================*/
  274.  
  275.  
  276.   /**
  277.    * Returns true/false to indicate whether a cache
  278.    * should be used
  279.    *
  280.    * @return true to use the cache, false otherwisea
  281.    */
  282.   static bool useCache();
  283.  
  284.   /**
  285.    * Returns the maximum age in seconds cached files should be
  286.    * kept before they are deleted as necessary.
  287.    *
  288.    * @return the maximum cache age in seconds
  289.    */
  290.   static int maxCacheAge();
  291.  
  292.   /**
  293.    * Returns the maximum size that can be used for caching.
  294.    *
  295.    * By default this function returns the DEFAULT_MAX_CACHE_SIZE
  296.    * value as defined in http_slave_defaults.h.  Not that the
  297.    * value returned is in bytes, hence a value of 5120 would mean
  298.    * 5 Kb.
  299.    *
  300.    * @return the maximum cache size in bytes
  301.    */
  302.   static int maxCacheSize(); // Maximum cache size in Kb.
  303.  
  304.   /**
  305.    * The directory which contains the cache files.
  306.    * @return the directory that contains the cache files
  307.    */
  308.   static QString cacheDir();
  309.  
  310.   /**
  311.    * Returns the Cache control directive to be used.
  312.    * @return the cache control value
  313.    */
  314.   static KIO::CacheControl cacheControl();
  315.  
  316.  
  317. /*============================ DOWNLOAD CONFIG ==============================*/
  318.  
  319.   /**
  320.    * Returns true if partial downloads should be
  321.    * automatically resumed.
  322.    * @return true to resume partial downloads
  323.    */
  324.   static bool autoResume();
  325.  
  326.   /**
  327.    * Returns true if partial downloads should be marked
  328.    * with a ".part" extension.
  329.    * @return true if partial downloads should get an ".part" extension
  330.    */
  331.   static bool markPartial();
  332.  
  333.   /**
  334.    * Returns the minimum file size for keeping aborted
  335.    * downloads.
  336.    *
  337.    * Any data downloaded that does not meet this minimum
  338.    * requirement will simply be discarded. The default size
  339.    * is 5 KB.
  340.    *
  341.    * @return the minimum keep size for aborted downloads in bytes
  342.    */
  343.   static int minimumKeepSize();
  344.  
  345.  
  346.   /*============================ NETWORK CONNECTIONS ==========================*/
  347.   /**
  348.    * Returns true if proxy connections should be persistent.
  349.    * @return true if proxy connections should be persistent
  350.    * @since 3.1
  351.    */
  352.   static bool persistentProxyConnection();
  353.  
  354.   /**
  355.    * Returns true if connections should be persistent
  356.    * @return true if the connections should be persistent
  357.    */
  358.   static bool persistentConnections();
  359.  
  360. /*=============================== OTHERS ====================================*/
  361.  
  362.  
  363.   /**
  364.    * Force a reload of the general config file of
  365.    * io-slaves ( kioslaverc).
  366.    */
  367.   static void reparseConfiguration();
  368.  
  369.   /**
  370.    * Return the protocol to use in order to handle the given @p url
  371.    * It's usually the same, except that FTP, when handled by a proxy,
  372.    * needs an HTTP ioslave.
  373.    *
  374.    * When a proxy is to be used, proxy contains the URL for the proxy.
  375.    * @param url the url to check
  376.    * @param proxy the URL of the proxy to use
  377.    * @return the slave protocol (e.g. 'http'), can be null if unknown
  378.    */
  379.   static QString slaveProtocol(const KURL &url, QString &proxy);
  380.  
  381.   /**
  382.    * @internal
  383.    * (Shared with SlaveConfig)
  384.    */
  385.   static KConfig *config();
  386. private:
  387.   static KConfig *http_config();
  388. };
  389. #endif
  390.